home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / catn / regexp.n < prev    next >
Text File  |  1994-09-20  |  7KB  |  199 lines
  1.  
  2.  
  3.  
  4. regexp(n)             Tcl Built-In Commands
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      regexp - Match a regular expression against a string
  12.  
  13. SYNOPSIS
  14.      regexp ?_s_w_i_t_c_h_e_s? _e_x_p _s_t_r_i_n_g  ?_m_a_t_c_h_V_a_r?  ?_s_u_b_M_a_t_c_h_V_a_r  _s_u_b_-
  15.      _M_a_t_c_h_V_a_r ...?
  16. _________________________________________________________________
  17.  
  18.  
  19. DESCRIPTION
  20.      Determines whether the regular expression _e_x_p  matches  part
  21.      or all of _s_t_r_i_n_g and returns 1 if it does, 0 if it doesn't.
  22.  
  23.      If additional arguments are specified after _s_t_r_i_n_g then they
  24.      are  treated  as  the  names of variables in which to return
  25.      information about  which  part(s)  of  _s_t_r_i_n_g  matched  _e_x_p.
  26.      _M_a_t_c_h_V_a_r will be set to the range of _s_t_r_i_n_g that matched all
  27.      of _e_x_p.  The first _s_u_b_M_a_t_c_h_V_a_r will contain  the  characters
  28.      in _s_t_r_i_n_g that matched the leftmost parenthesized subexpres-
  29.      sion within _e_x_p, the next _s_u_b_M_a_t_c_h_V_a_r will contain the char-
  30.      acters  that matched the next parenthesized subexpression to
  31.      the right in _e_x_p, and so on.
  32.  
  33.      If the initial arguments to regexp start with  -  then  they  |
  34.      are   treated  as  switches.   The  following  switches  are  |
  35.      currently supported:                                          |
  36.  
  37.      -nocase                                                            ||
  38.                Causes  upper-case  characters  in  _s_t_r_i_n_g  to  be  |
  39.                treated as lower case during the matching process.  |
  40.  
  41.      -indices                                                           ||
  42.                Changes   what  is  stored  in  the  _s_u_b_M_a_t_c_h_V_a_rs.  |
  43.                Instead of storing the  matching  characters  from  |
  44.                string,  each  variable will contain a list of two  |
  45.                decimal strings giving the indices  in  _s_t_r_i_n_g  of  |
  46.                the  first  and  last  characters  in the matching  |
  47.                range of characters.                                |
  48.  
  49.      --                                                                 ||
  50.                Marks the end of switches.  The argument following  |
  51.                this one will be treated as _e_x_p even if it  starts  |
  52.                with a -.
  53.  
  54.      If there are more _s_u_b_M_a_t_c_h_V_a_r's  than  parenthesized  subex-
  55.      pressions  within  _e_x_p,  or if a particular subexpression in
  56.      _e_x_p doesn't match the string (e.g. because it was in a  por-
  57.      tion  of  the  expression  that  wasn't  matched),  then the
  58.      corresponding _s_u_b_M_a_t_c_h_V_a_r  will  be  set  to  ``-1  -1''  if
  59.      -indices has been specified or to an empty string otherwise.
  60.  
  61.  
  62.  
  63. Tcl                                                             1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. regexp(n)             Tcl Built-In Commands
  71.  
  72.  
  73.  
  74. REGULAR EXPRESSIONS
  75.      Regular expressions are implemented  using  Henry  Spencer's
  76.      package  (thanks,  Henry!),  and  much of the description of
  77.      regular expressions below is copied verbatim from his manual
  78.      entry.
  79.  
  80.      A regular expression is zero or more _b_r_a_n_c_h_e_s, separated  by
  81.      ``|''.    It  matches  anything  that  matches  one  of  the
  82.      branches.
  83.  
  84.      A branch is zero or more _p_i_e_c_e_s, concatenated.  It matches a
  85.      match  for  the  first,  followed by a match for the second,
  86.      etc.
  87.  
  88.      A piece is an _a_t_o_m possibly followed  by  ``*'',  ``+'',  or
  89.      ``?''.  An atom followed by ``*'' matches a sequence of 0 or
  90.      more matches of the atom.  An atom followed by ``+'' matches
  91.      a  sequence  of 1 or more matches of the atom.  An atom fol-
  92.      lowed by ``?'' matches a match of  the  atom,  or  the  null
  93.      string.
  94.  
  95.      An atom is a regular expression in parentheses  (matching  a
  96.      match  for  the  regular  expression),  a _r_a_n_g_e (see below),
  97.      ``.'' (matching any single character), ``^''  (matching  the
  98.      null  string  at  the  beginning of the input string), ``$''
  99.      (matching the null string at the end of the input string), a
  100.      ``\''  followed by a single character (matching that charac-
  101.      ter), or a  single  character  with  no  other  significance
  102.      (matching that character).
  103.  
  104.      A _r_a_n_g_e is a sequence of characters enclosed in ``[]''.   It
  105.      normally matches any single character from the sequence.  If
  106.      the sequence begins with ``^'', it matches any single  char-
  107.      acter  _n_o_t from the rest of the sequence.  If two characters
  108.      in the sequence are separated by ``-'',  this  is  shorthand
  109.      for  the  full  list  of ASCII characters between them (e.g.
  110.      ``[0-9]'' matches any decimal digit).  To include a  literal
  111.      ``]''  in the sequence, make it the first character (follow-
  112.      ing a possible ``^'').  To include a literal ``-'', make  it
  113.      the first or last character.
  114.  
  115.  
  116. CHOOSING AMONG ALTERNATIVE MATCHES
  117.      In general there may be more than one way to match a regular
  118.      expression  to  an  input string.  For example, consider the
  119.      command
  120.  
  121.           regexp  (a*)b*  aabaaabb  x  y
  122.  
  123.      Considering only the rules given so far, x and y  could  end
  124.      up  with  the values aabb and aa, aaab and aaa, ab and a, or
  125.      any of several other combinations.  To resolve  this  poten-
  126.      tial  ambiguity  regexp chooses among alternatives using the
  127.  
  128.  
  129.  
  130. Tcl                                                             2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. regexp(n)             Tcl Built-In Commands
  137.  
  138.  
  139.  
  140.      rule ``first then longest''.  In other  words,  it  consders
  141.      the  possible  matches  in  order working from left to right
  142.      across the input string and the pattern, and it attempts  to
  143.      match longer pieces of the input string before shorter ones.
  144.      More specifically, the following rules apply  in  decreasing
  145.      order of priority:
  146.  
  147.      [1]  If a regular expression could match two different parts
  148.           of  an  input  string  then  it will match the one that
  149.           begins earliest.
  150.  
  151.      [2]  If a regular expression contains | operators  then  the
  152.           leftmost matching sub-expression is chosen.
  153.  
  154.      [3]  In *, +, and ? constructs, longer matches are chosen in
  155.           preference to shorter ones.
  156.  
  157.      [4]  In sequences of expression  components  the  components
  158.           are considered from left to right.
  159.  
  160.      In the example from above, (a*)b*  matches  aab:   the  (a*)
  161.      portion  of the pattern is matched first and it consumes the
  162.      leading aa; then the b* portion of the pattern consumes  the
  163.      next b.  Or, consider the following example:
  164.  
  165.           regexp  (ab|a)(b*)c  abc  x  y  z
  166.  
  167.      After this command x will be abc, y will be ab, and  z  will
  168.      be an empty string.  Rule 4 specifies that (ab|a) gets first
  169.      shot at the input string and Rule 2 specifies  that  the  ab
  170.      sub-expression is checked before the a sub-expression.  Thus
  171.      the b has already been claimed before the (b*) component  is
  172.      checked and (b*) must match an empty string.
  173.  
  174.  
  175. KEYWORDS
  176.      match, regular expression, string
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Tcl                                                             3
  196.  
  197.  
  198.  
  199.